Psemaphore(2)             Jan. 6, 1992              Psemaphore(2)



NAME
     Psemaphore - create / use / destroy a sempahore

SYNOPSIS
     LONG Psemaphore( WORD mode, LONG id, long timeout )

DESCRIPTION
     Psemaphore is a call that implements uncounted semaphores. A
     semaphore  is used for mutual exclusion: only one process at
     a time may "own" a given semaphore.

     For example, a semaphore may be used to  protect  access  to
     data  structures  which  are  in shared memory and which are
     used by multiple threads in  a  process:  before  using  the
     memory  a  thread  must gain ownership of the guarding sema-
     phore, and when finished the thread must release  the  sema-
     phore.  The semaphore would be created during initialization
     and destroyed during shutdown.

     Semaphores are identified by an id, which  is  an  arbitrary
     longword.   This  is  the semaphore's "name." The id used to
     create the semaphore is the "name" of  that  semaphore  from
     then  on.  When using semaphores, you should strive to use a
     longword that is unique. Using four ASCII  characters  which
     spell  out  something  is  common:  0x4b4f444f  ("MODM") for
     instance might be the id of a semaphore that controls access
     to  a  modem.  (Actually, this would be a poor choice, since
     there can be more than one modem in a system and this  sema-
     phore ID isn't flexible enough to handle that.  "MDM1" might
     be better.)

     Semaphore id's beginning with 0x5f (the  underscore  charac-
     ter) are reserved for operating system use.

     The timeout argument is only used in Mode 2. It  is  ignored
     in  other  modes.  A  timeout  of zero means "return immedi-
     ately."  A value of -1 means "forever" - that is, never time
     out.  Other  values are a number of milliseconds to wait for
     the semaphore before timing out.

     The mode argument is used to tell what operation the  caller
     desires:

     MODE ACTION

     0    Create and "get" a semaphore with the given ID.

     1    Destroy the indicated semaphore. The  caller  must  own
          the semaphore prior to making this call.

     2    Request ownership of the semaphore.  Blocks  until  the
          semaphore  is  free  or  until the timeout expires. See



Version 0.92  Last change: MiNT Programmer's Manual             1






Psemaphore(2)             Jan. 6, 1992              Psemaphore(2)



          below.

     3    Release the semaphore. The caller must  own  the  sema-
          phore prior to making this call.

RETURNS
     CODE MEANING

     0    Success.

     ERROR
          A request for a  semaphore  which  the  caller  already
          owns.

     ERANGE
          The semaphore does not exist.

     EACCDN
          Failure. The semaphore already  exists  (mode  0),  you
          don't  own it (modes 1 and 3), or the request timed out
          (mode 2).


NOTES
     When you create a semaphore you also own  it,  so  you  must
     release  it  before  anybody  else  can  get  it. If you are
     blocked waiting for a semaphore (mode 2 before  the  timeout
     expires)  and somebody destroys the semaphore, the call will
     return ERANGE to you (because the requested  semaphore  does
     not exist any more!).

     When a  process  terminates,  any  semaphores  it  owns  are
     released.

     At most one process may own a semaphore.  Ownership  is  not
     inherited by children (fork()) or across exec().

     Once created, semaphores are  never  destroyed  except  upon
     request.  Thus  if  a  program  creates a semaphore and then
     crashes the semaphore will never go away.

     Semaphores can be implemented using  named  pipes  and  file
     locking.  Technically,  then, semaphores are redundant.  The
     facility is included as a kernel call because it was  deemed
     necessary to have this kind of exclusion available with lit-
     tle persistent state or system-call overhead.









Version 0.92  Last change: MiNT Programmer's Manual             2